Repository navigation
Conversation
Add NOISE_LEARNING.md: how to estimate the 25-parameter noise model from detector data with cudaq-qec 0.9.0 (nv_qldpc.learn_noise, parametric mode) and write it as a data.noise_model block for training. Link it from the "Noise model" section of the README. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Signed-off-by: Ivan Basov <ibasov@nvidia.com>
bmhowe23
left a comment
There was a problem hiding this comment.
Thanks, this is a useful page. I ran the Python block verbatim against cudaq-qec-cu12==0.9.0 and it reproduces the numbers in the description (rank 23 of 25 per basis; prep/meas/idle within 3%; 14 of 15 CNOT parameters within 20%).
One issue with how the two bases are merged (first inline comment), plus a few smaller doc points. The comment on the "Parameter names" note points at a naming inconsistency in this repo that predates the PR.
Limits of my own checks:
- The unidentified directions mentioned in the comments on the merge loop and the "Use both bases" note were checked at d=3 and d=5 for the
XVorientation only. - I did not check whether training mixes bases under one
data.noise_model. If it does, the "one block per basis" advice needs rethinking. - For the surface-code / color-code naming comment I read the two circuit builders only. I did not check which convention
precompute_demor the training-data generator follow, and I did not run the color-code path.
| # Preparation and measurement parameters come from the experiment in their own basis, | ||
| # every other parameter from the runs that identify it on its own. | ||
| noise_model = {} | ||
| for k in p25.P25_PARAM_NAMES: | ||
| if k in SWAP: | ||
| runs = [k[-1]] | ||
| else: | ||
| runs = [b for b in learned if identifiable[b][k]] or list(learned) | ||
| noise_model[k] = float(np.mean([learned[b][k] for b in runs])) |
There was a problem hiding this comment.
For training on one basis, I'd skip this merge and write each run's 25 values as its own block (e.g. learned_noise_model_Z.yaml, learned_noise_model_X.yaml). A single-basis run reproduces that basis's detector statistics exactly, even though some values are not individually determined. The merge here mixes values across runs: p_prep_Z/p_meas_Z from the Z run are only fixed together with p_cnot_XI/p_cnot_XX, which this loop takes from the X run (mirror for X with p_cnot_IZ/p_cnot_ZZ). With those CNOT rates unequal (d=5, 524k shots per basis, true p_cnot_XI=1.5e-3, p_cnot_XX=1e-4) I get p_prep_Z at 0.53x of truth in the merged model, and the merged set no longer matches either basis.
There was a problem hiding this comment.
Agreed, the merge was wrong. Reproduced with p_cnot_XI = 1.5e-3, p_cnot_XX = 1e-4, d=5, 524k shots: p_prep_Z at 0.80x, p_meas_Z at 1.42x, and Z-basis mechanism rates off by up to about 20%. The numbers in the first version held only because the example's true p_cnot_XI and p_cnot_XX are nearly equal.
On one block per basis: public training always generates both bases from one data.noise_model (code/workflows/config_validator.py sets meas_basis = "both" and rejects a user override), so per-basis files cannot be used there. I kept one block and replaced the merge with a joint fit: the one set of 25 parameters that reproduces the mechanism rates learned in both runs (bounded least squares on the relative error). The stacked design of the two bases has rank 25.
Result of the block as written (d=7, 262,144 shots per basis), with true p_cnot_XI = p_cnot_ZZ = 1.5e-3 and p_cnot_XX = p_cnot_IZ = 1e-4: prep/meas within 3%, the two large CNOT values within 3%, the two small ones at 1.22x and 1.32x, mechanism rates within 2.2% of the true model in each basis.
Changed in 21baead.
| - **Use both bases.** One memory basis fixes 23 of the 25 parameter combinations. | ||
| `report["q_identifiable"]` marks the parameters that one experiment does not determine on | ||
| their own: the four preparation and measurement parameters and two CNOT parameters, a | ||
| different pair in each basis. A Z-basis experiment sees `p_prep_X` and `p_meas_X` only as | ||
| a sum and returns the same value for both; an X-basis experiment does the same for | ||
| `p_prep_Z` and `p_meas_Z`. The example therefore takes each preparation and measurement | ||
| parameter from the experiment in its own basis, and every other parameter from the runs | ||
| that identify it. |
There was a problem hiding this comment.
Suggest reframing: a model learned from one basis is valid for generating data in that basis. Its prep/meas values and two CNOT values (p_cnot_XI/p_cnot_XX for Z, p_cnot_IZ/p_cnot_ZZ for X) are not the device's individual rates and should not be used for the other basis or quoted as device characterization.
There was a problem hiding this comment.
Rewritten along these lines in 21baead: the values learned from one basis reproduce the detector statistics of that basis, the six non-identifiable ones are not the device's individual rates, and they should not be used for the other basis or quoted as a characterization. I also added a separate note, "One noise model for both bases", on why training needs one set and why the two results must not be combined parameter by parameter.
| that the result can be compared with the truth. For a device, replace `dets` with the recorded | ||
| data: a `uint8` array of shape `[shots, detectors]`, with detectors in the order of the | ||
| circuit built by `MemoryCircuit` for the same distance, rounds, basis and orientation. |
There was a problem hiding this comment.
Detector order is necessary but not sufficient. The design is built from the fault locations of the MemoryCircuit circuit, so the device must have run that same schedule (CNOT order, idle placement, Z-basis measure/reset on ancillas). With a different schedule the data still has the right shape and learn_noise still runs, but rates are attributed to the wrong parameters. Worth one sentence here.
There was a problem hiding this comment.
Added in 21baead, after the sentence on detector order. One difference from the wording here: the surface builder does not use Z-basis reset/measure on all ancillas. It emits RX/MRX for X-stabilizer ancillas and R/MR for Z-stabilizer ancillas, with no Hadamards, so the sentence lists the CNOT order, the idle locations, and ancilla preparation and measurement in the X basis for X stabilizers and in the Z basis for Z stabilizers.
| - **Parameter names.** In this repository `p_prep_Z` and `p_meas_Z` are the failure | ||
| probabilities of a Z-basis preparation and measurement (an X flip). `cudaq_qec`'s `p25` | ||
| helpers name the same parameters by the applied Pauli (`p_prep_X`, `p_meas_X`). The `swap` | ||
| step in the example converts between the two; without it `p25.design_map` rejects the |
There was a problem hiding this comment.
"In this repository p_prep_Z and p_meas_Z are the failure probabilities of a Z-basis preparation and measurement" holds for the surface-code builder only. The color-code builder reads the same four keys the other way:
code/qec/surface_code/memory_circuit.py(add_reset,add_measure): Z-basis reset/measure getsX_ERROR(p_prep_Z)/X_ERROR(p_meas_Z). This matches the comments inconf/config_public.yaml.code/qec/color_code/memory_circuit.py:558-566and:844-852: Z-basis reset/measure getsX_ERROR(p_prep_X)/X_ERROR(p_meas_X).
The shipped configs set all four values equal, so this is invisible today, but a learned (non-uniform) model makes it matter. Not something to fix in this PR; suggest scoping the sentence to "the surface-code circuits of this repository" and opening a separate issue for the color-code builder. It also means the cudaq-qec p25 naming agrees with the color-code builder, so the swap step is specific to surface code.
There was a problem hiding this comment.
Confirmed in both builders. In 21baead the sentence is scoped to the surface-code circuits of this repository, the note says the swap step is specific to them, and the "Surface code only" note now states that the color-code circuits read the four prep/meas keys the other way. The color-code builder itself is not touched here; it is a separate issue.
There was a problem hiding this comment.
Follow-up: instead of an issue, I am fixing the color-code builder in a separate PR. It moves the color-code path to the surface-code convention (a key is named by the basis that fails), which is what conf/config_public.yaml and the README describe; the surface builder and the config stay as they are. I will link it here once it is open. When it merges, the sentence in this guide about the color-code circuits reading the keys the other way will be updated.
| circuit. Because of this, the `--tag-circuit` and `--yaml` options of the | ||
| `cudaq_qec.plugins.nv_qldpc.cli.learn_physical_params` command-line tool write the four | ||
| prep/meas keys exchanged for this repository. |
There was a problem hiding this comment.
Nit: --tag-circuit does not write anything. Suggest: "The learn_physical_params command-line tool rejects a tag circuit built by MemoryCircuit from unswapped tags, and with swapped tags its --yaml output has the four prep/meas keys exchanged for this repository."
There was a problem hiding this comment.
Applied this wording in 21baead. I also ran the tool on these circuits: a tag circuit built from unswapped tags is rejected with the same ValueError as p25.design_map, and with swapped tags the --yaml output has the four prep/meas keys exchanged.
Address review comments on the noise learning guide. The example combined the two single-basis results parameter by parameter. One memory basis fixes the preparation and measurement parameters only together with two CNOT parameters, so values taken from different runs do not form a consistent set. The example now fits the one set of 25 parameters that reproduces the mechanism rates learned in both bases; the two experiments together fix all 25. Also state that the device must run the MemoryCircuit schedule, scope the parameter-name note and the swap step to the surface-code circuits, say what a single-basis result can be used for, and correct the description of the learn_physical_params command-line tool. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Signed-off-by: Ivan Basov <ibasov@nvidia.com>
|
@bmhowe23 thanks for the review. All five comments are addressed in 21baead, with a reply in each thread; the PR description has the updated verification numbers. Could you take another look? The main change is the example: the per-parameter merge of the two bases is replaced by one fit of the 25 parameters to the results of both bases. The answer to the open question in the review is that public training always uses both bases under one The change is documentation only. Unit tests and the style checks pass on 21baead; the GPU jobs are still running. |
What
Documentation only.
NOISE_LEARNING.md: how to estimate the 25-parameter circuit-level noise model from detector data with CUDA-Q QEC noise learning (cudaq_qec.plugins.nv_qldpc.learn_noise,mode="parametric", released in cudaq-qec 0.9.0) and write the result as adata.noise_modelblock for pre-decoder training.README.mdthat links to it.Why
data.noise_modelis the input of training-data generation. When the device rates are unknown, they can be learned from recorded detector data without logical labels. The feature lives in CUDA-Q QEC; this page shows how to use it with the circuits and the config of this repository, and links to the CUDA-Q QEC documentation for the method itself.For reviewers
X_ERROR(p_prep_Z)after a Z-basis reset). Thep25helpers in cudaq-qec 0.9.0 name it by the applied Pauli and acceptX_ERRORonly forp_prep_X/p_meas_X. Without a conversion,p25.design_maprejects a tag circuit built byMemoryCircuit:ValueError: X_ERROR component X tagged as p_prep_Z: inconsistent with the circuit builder's conventions.The example exchanges the four keys when it builds the tag circuit and again on export, and the Notes section explains this. If the convention is aligned later on either side, the
swapstep can be removed. The color-code circuits read the four keys the other way; the guide says so and does not cover them.p_prep_Zandp_meas_Zare fixed only together withp_cnot_XIandp_cnot_XX, andp_prep_Xandp_meas_Xonly as a sum; the X basis mirrors this withp_cnot_IZandp_cnot_ZZ. The two bases together give rank 25.data.noise_model(config_validator.pysetsmeas_basis = "both"and rejects an override), so one block per basis cannot be used. The example fits the one set of 25 parameters that reproduces the mechanism rates learned in both bases (bounded least squares on the relative error, about ten lines with SciPy, which the inference requirements already include).Changes after review
The first version combined the two single-basis results parameter by parameter (preparation and measurement from the run in their own basis, CNOT from the run that identifies them). That mixes values that are consistent only as a set, and the reported accuracy held only because the example's true
p_cnot_XIandp_cnot_XXare nearly equal. Withp_cnot_XI = 1.5e-3andp_cnot_XX = 1e-4that merge gavep_prep_Zat 0.80x andp_meas_Zat 1.42x of the truth, and mechanism rates off by up to about 20% in the Z basis. It is replaced by the joint fit above. Also changed: a sentence that the device must run theMemoryCircuitschedule, the parameter-name note scoped to the surface-code circuits, what a single-basis result can be used for, and the description of thelearn_physical_paramscommand-line tool.Verification
The Python block was extracted verbatim from
NOISE_LEARNING.mdand run from the repository root on this branch:cudaq-qec-cu120.9.0 from PyPI, stim 1.16.0, Python 3.11, one RTX PRO 6000.p_cnot_XI = p_cnot_ZZ = 1.5e-3andp_cnot_XX = p_cnot_IZ = 1e-4: preparation and measurement within 3%, the two large CNOT parameters within 3%, the two small ones at 1.22x and 1.32x; 13 of 15 CNOT parameters within 20%; mechanism rates within 2.2% in each basis.noise_model_from_configon top ofconf/config_public.yaml.learn_physical_paramswas run on these circuits: a tag circuit from unswapped tags is rejected with the error above; with swapped tags the--yamloutput has the four prep/meas keys exchanged.Not covered: a training run on the learned noise model, and detector data from a device (the example simulates the data).
No code, test or dependency changes.
🤖 Generated with Claude Code